home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr05 / wrshd12.zip / WRSHD.DOC < prev    next >
Text File  |  1995-01-17  |  50KB  |  1,124 lines
  1. Winsock RSHD                                       Version 1.2
  2. Copyright 1994 Denicomp Systems
  3. All Rights Reserved
  4.   
  5.   
  6. DESCRIPTION
  7. -----------
  8.   
  9. Winsock RSHD ("Remote Shell Daemon") is a daemon (server) that accepts
  10. requests for command execution from other hosts on the network and executes
  11. them on the PC running Winsock RSHD.  It runs under Microsoft Windows 3.1
  12. and Windows Sockets compatible TCP/IP stacks.
  13.  
  14. Winsock RSHD is similar to the Unix server of the same name, but provides
  15. some special functionality for the Windows environment, such as:
  16.  
  17.      - Ability to send keystrokes to the command running under Windows
  18.      - Support for the "rcp" command to allow copying to and from the PC
  19.      - Security mechanism to allow/deny access for hosts and users
  20.      - Ability to capture standard output and standard error from DOS commands
  21.  
  22. Command requests can come from hosts running other operating systems such as
  23. Unix or from other PC's using the standard "rsh" utility that comes with your
  24. TCP/IP package or Winsock RSH, also available from Denicomp Systems.
  25.  
  26. Files can be copied to the PC or from the PC running Winsock RSHD using the
  27. standard TCP/IP "rcp" command.  This includes the "rcp" command available
  28. with Unix or a PC-based "rcp" command such as Winsock RCP, also available from
  29. Denicomp Systems.
  30.    
  31.  
  32.  
  33. REQUIREMENTS
  34. ------------
  35.  
  36. Winsock RCP requires a PC running Windows 3.1 or higher and a Windows Sockets
  37. compatible TCP/IP stack.  Winsock RSHD has been tested with the following:
  38.  
  39.        Microsoft 32-bit TCP/IP for Windows
  40.        Wollongong Pathway Access
  41.        Novell LAN Workplace for DOS Version 4.2
  42.  
  43. To work with Novell LAN Workplace for DOS, you must have version 4.2 or later
  44. and a WINSOCK.DLL file dated 10/07/94 or later.
  45.  
  46. You also must have the file VBRUN300.DLL installed on your system.  This file
  47. must be in a directory included in your PATH environment variable.  This file
  48. is NOT included with Winsock RSHD.  It can be obtained from a number of BBS
  49. systems and online services.  If you cannot obtain it, please contact Denicomp
  50. Systems for assistance.
  51.  
  52.  
  53. WINSOCK RSHD INSTALLATION
  54. -------------------------
  55.  
  56. To install with Winsock RSHD, use PKUNZIP to uncompress the distribution file
  57. into a directory on your hard disk or onto a diskette.
  58.  
  59. Then use File/Run from the Windows Program Manager menu.  Enter the drive and
  60. directory name that contains the uncompressed files, followed by "SETUP".
  61.  
  62. For example, if you uncompressed Winsock RSHD into the directory C:\WRSHD,
  63. type C:\WRSHD\SETUP.
  64.  
  65. Winsock WRSHD by default will be installed in the C:\WRSHD directory.  You
  66. can specify a different directory if you wish.
  67.  
  68. The Winsock Utilities group will be created.  Icons will be in this group for
  69. Winsock RSHD, along with options to view/print the order form and the manual
  70. for using Winsock RSHD.
  71.  
  72. If you wish to start Winsock RSHD automatically each time you run Windows,
  73. you can copy or move the Winsock RSHD icon to the Windows Start Up program
  74. group.
  75.  
  76.  
  77. WINSOCK RSHD CONFIGURATION
  78. --------------------------
  79.  
  80. You configure Winsock RSHD by double clicking on the Winsock RSHD Configuration
  81. icon in the Winsock Utilities program group.
  82.  
  83. Winsock RSHD may work properly without configuration, depending on the TCP/IP
  84. software you are using and whether or not you wish to enforce security.
  85.  
  86. You must configure Winsock RSHD if:
  87.  
  88.    1) You are using Microsoft's 32-bit TCP/IP for Windows.  You should select
  89.       Method 2 for the Method of Operation option.
  90.  
  91.    2) You wish to enforce security.  That is, you wish to specify which hosts
  92.       and/or users may or may not access the PC through Winsock RSHD.  By
  93.       default, no security is enforced.
  94.  
  95. Otherwise, configuration is not necessary for Winsock RSHD to run, but you may
  96. want to examine the options available.
  97.  
  98. Also note that by using the default Winsock RSHD configuration, you may see
  99. "Warning" messages on the Winsock RSHD screen, especially if your TCP/IP
  100. software does not support an option called "Reuse Address".  You can ignore
  101. this warning if you see it; Winsock RSHD will continue to operate properly.
  102. You can stop the message by setting all "ReuseAddr" options to -1.
  103.  
  104. In the Winsock RSHD Configuration screen, set the desired options, then click
  105. on "OK" to save the configuration and exit.  Click on "Cancel" to discard any
  106. changes you have made and exit.  Click on "Edit Security" to edit the Security
  107. File you have specified using the Windows Notepad editor.  This only works if
  108. you have specified a Security File name.
  109.  
  110. The Winsock RSHD Configuration screen contains the following options:
  111.  
  112.  
  113. Method of Operation:                             (Default: Method 1)
  114.  
  115.        Winsock RSHD has two methods of operation: Method 1 and 2.  The method
  116.        you should use depends on the TCP/IP stack you are using.  Ideally,
  117.        Winsock RSHD should just work, no matter what TCP/IP stack you are
  118.        using.  However, practice shows that there are some internal differences
  119.        in Windows Sockets implementations, especially when implementing servers.
  120.  
  121.        If the default Method 1 does not work (you receive error messages),
  122.        try Method 2.  If neither method works, you can fiddle with the
  123.        Advanced Configuration Options explained later or contact Denicomp
  124.        Systems for assistance.
  125.  
  126.        In general, Method 1 should work with most TCP/IP stacks.  This includes
  127.        Wollongong Pathway Access and Novell LAN Workplace for DOS.  Method 2
  128.        works well with Microsoft's 32-bit TCP/IP for Windows.
  129.    
  130.        Although Method 1 will also work with Microsoft's TCP/IP, it has been
  131.        known to lock up the PC with heavy use, so Method 2 is recommended.
  132.  
  133.  
  134. Minimize on Startup:                             (Default: Not Checked)
  135.  
  136.        If this option is checked, Winsock RSHD will be minimized when it
  137.        starts.  If it is not, you will see the Winsock RSHD window.  The
  138.        Winsock RSHD window displays information about connections, commands
  139.        executed, and any error messages.
  140.  
  141. Message Level:                                   (Default: 0)
  142.  
  143.        Specifies the level of detail of the messages displayed in the
  144.        Winsock RSHD window.  The default level is 0, which gives the least
  145.        amount of detail.  Level 0 will show you when someone receives an error
  146.        trying to execute a command or is denied permission.  Level 1 provides
  147.        more detail about the various stages of Winsock RSHD execution.  Level 2
  148.        provides the highest level of detail.  Levels 1 and 2 are useful if you
  149.        are having problems with Winsock RSHD execution.
  150.  
  151. Security File:                                   (Default: None)
  152.  
  153.        Specify the full path name of the Security File used by Winsock RSHD
  154.        to enforce security (allow and deny users and hosts).  The format of
  155.        this file is explained in more detail later.  If you do not specify a
  156.        Security File, all users and hosts will be granted access to execute
  157.        commands and transfer files to and from your PC.  If the Security File
  158.        you specify does not exist, NO users or hosts will be granted access.
  159.  
  160.        If you do not wish to enforce any security, do not specify a filename.
  161.  
  162. Request Log:                                     (Default: None)
  163.  
  164.        This option allows you to log all requests (commands to be executed)
  165.        in a file you specify.  Each time someone attempts to execute a command
  166.        on the PC, the date and time, the user name, the host name, and the
  167.        command will be written to this file.
  168.  
  169. Deny Log:                                        (Default: None)
  170.  
  171.        This option allows you to log all permission violations in a file you
  172.        specify.  Each time someone is denied permission to execute a command
  173.        on the PC, the date and time, the user name, the host name, and the
  174.        command will be written to this file.
  175.  
  176. Error Log:                                       (Default: None)
  177.  
  178.        This option allows you to log all command execution errors in a file
  179.        you specify.  Each time someone receives an error trying to execute
  180.        a command on the PC, the date and time, the user name, the host name,
  181.        the command, and error message will be written to this file.  These
  182.        are errors that occur after the user has been granted permission to
  183.        execute the command.  For example, an error would be logged if a program
  184.        was to be run that did not exist.
  185.  
  186. NOTE: Each of the log files may refer to the same file name if you wish.
  187.       They will not overwrite each other.  Each message is appended to the
  188.       end of the file.  You should be sure to periodically delete the log
  189.       file(s) because they can get large over time on an actively used PC.
  190.  
  191.  
  192. ADVANCED CONFIGURATION OPTIONS
  193. ------------------------------
  194.  
  195. These configuration options are for advanced users and do not normally
  196. require deviations from their default values.  Full understanding of them
  197. require an understanding of TCP/IP and Windows Sockets operation and
  198. programming.
  199.  
  200. Some options refer to TCP/IP option set on "sockets" used by Winsock RSHD.
  201. Sockets are connections over the network.  Winsock RSHD uses three sockets:
  202.  
  203.      Listen:  Listens for connections.
  204.  
  205.      Conn:    Socket created when a connection is made to receive parameters
  206.               from the "rsh" or "rcp" command.
  207.  
  208.      Stderr:  Socket created to send error messages back to the remote host.
  209.  
  210.  
  211. The advanced options are:
  212.  
  213. Port:                                            (Default: 514)
  214.  
  215.        Specifies the port number that Winsock RSHD listens to for
  216.        connections.  The standard port for the Remote Shell daemon is 514.
  217.  
  218. RCP Block Size:                                  (Default: 1024)
  219.  
  220.        Specifies the number of bytes in a block of data that the Remote Copy
  221.        (RCP) service of Winsock RSHD processes at one time.  When files are
  222.        copied to the PC, it reads from the network and writes to the disk in
  223.        blocks of this size.  When files are copied from the PC, it reads from
  224.        the disk and writes to the network in blocks of this size.  Note that
  225.        this is an internal block size only; it does not change any TCP/IP
  226.        parameters.
  227.  
  228. Listen Backlog:                                  (Default: 5)
  229.  
  230.        The number of requests that can be "backlogged" when Winsock RSHD is
  231.        listening for connections.  The minimum is 1; the maximum is usually 5.
  232.  
  233. Listen Shutdown:                                 (Default: 2)
  234.  
  235.        Specifies how the "Listen" socket is to be shutdown before it
  236.        is closed.  A value of 0 means that it is not shutdown.  A value
  237.        of 1 halts all receiving before shutting down.  A value of 2 halts
  238.        all sending and receiving before shutting down.
  239.  
  240. Listen Linger:                                   (Default: -1)
  241.  
  242.        If this option is set to "0", the TCP/IP "linger" option will be turned
  243.        off for the "Listen" socket.  If this option is set to a value greater
  244.        than zero, the linger option will be turned on and the timeout value
  245.        will be set to the value you assign this option.  If this option is
  246.        set to "-1" or does not appear in the configuration file, no linger
  247.        options will be set; the default linger option specified by your TCP/IP
  248.        package will be in effect.
  249.  
  250. Listen KeepAlive:                                (Default: -1)
  251.  
  252.        If this option is set to "0", the TCP/IP "keepalive" option will be
  253.        turned off for the "Listen" socket.  If this option is set to "1",
  254.        the keepalive option will be turned on.  If this option is set to "-1" or
  255.        does not appear in the configuration file, no keepalive option will be
  256.        set; the default keepalive option specified by your TCP/IP package will
  257.        be in effect.
  258.  
  259. Listen ReuseAddr:                                (Default: 1)
  260.  
  261.        If this option is set to "0", the TCP/IP "ReuseAddr" option (Reuse
  262.        Address) will be turned off for the "Listen" socket.  If this option is
  263.        set to "1", the ReuseAddr option will be turned on.  If this option is
  264.        set to "-1" or does not appear in the configuration file, no ReuseAddr
  265.        option will be set; the default ReuseAddr option specified by your
  266.        TCP/IP package will be in effect.
  267.  
  268. Connection Shutdown:                             (Default: -1)
  269.  
  270.        Sets the "shutdown" option for the connection socket.  See the
  271.        Listen Shutdown option for an explanation of the valid values.
  272.  
  273. Connection Linger:                               (Default: -1)
  274.  
  275.        Sets the "linger" option for the connection socket.  See the Listen
  276.        Linger option for an explanation of the valid values.
  277.  
  278. Connection KeepAlive:                            (Default: -1)
  279.  
  280.        Sets the "keepalive" option for the connection socket.  See the
  281.        Listen KeepAlive option for an explanation of the valid values.
  282.  
  283. Connection ReuseAddr:                            (Default: 1)
  284.  
  285.        Sets the "ReuseAddr" option for the connection socket.  See the
  286.        Listen ReuseAddr option for an explanation of the valid values.
  287.  
  288. Stderr Linger:                                   (Default: -1)
  289.  
  290.        Sets the "linger" option for the standard error socket.  See the
  291.        Listen Linger option for an explanation of the valid values.
  292.  
  293. Stderr KeepAlive:                                (Default: -1)
  294.  
  295.        Sets the "keepalive" option for the standard error socket.  See the
  296.        Listen KeepAlive option for an explanation of the valid values.
  297.  
  298. Stderr ReuseAddr:                                (Default: 1)
  299.  
  300.        Sets the "ReuseAddr" option for the standard error socket.  See the
  301.        Listen ReuseAddr option for an explanation of the valid values.
  302.  
  303. Stderr Shutdown:                                 (Default: 2)
  304.  
  305.        Sets the "shutdown" option for the standard error socket.  See the
  306.        Listen Shutdown option for an explanation of the valid values.
  307.  
  308. WINSOCK RSHD SECURITY FILE
  309. --------------------------
  310.  
  311. With Unix, security is enforced on remote command execution using a
  312. combination of the password file (/etc/passwd), the hosts file (/etc/hosts),
  313. and the host equivalency files (/etc/hosts.equiv and $HOME/.rhosts).
  314.  
  315. Windows 3.1 does not have any security measures at all.  If Winsock RSHD
  316. did not provide for security, any host and user could execute commands through
  317. Winsock RSHD or copy files to and from the PC using the "rcp" command.
  318.  
  319. Winsock RSHD enforces security through its Security File.  The name of this
  320. file is specified in the Winsock RSHD Configuration as the Security File.
  321.  
  322. If you specify a Security File name and the file does not exist or the file is
  323. completely empty, all hosts and users are denied access.
  324.  
  325. Conversely, if you do not specify a Security File, all hosts and users are
  326. granted access.  So if you do not wish to enforce any security, do not specify
  327. a Security File name.
  328.  
  329. You create the Security File using a text editor.  It consists of lines that
  330. specify who may or may not access the PC using Winsock RSHD.  The following
  331. are the options available in the Security File:
  332.  
  333.    #
  334.            Any line beginning with # is treated as a comment and is ignored.
  335.  
  336.    +
  337.            A plus sign (+) on a line by itself specifies that ALL hosts and
  338.            users are granted permission.  This is useful if you wish to allow
  339.            many hosts and users, but deny only a few.  Use the deny options
  340.            on subsequent lines.
  341.  
  342.    host
  343.  
  344.            You can specify a host that is granted permission by entering the
  345.            name of the host on a line by itself.  ALL users on that host are
  346.            granted permission, unless you specifically deny those users on
  347.            subsequent lines.
  348.  
  349.            You may also use the IP address of the host instead (the dotted-
  350.            decimal representation).  If you specify the name of the host,
  351.            that name must appear in the HOSTS file used by your TCP/IP package.
  352.  
  353.    !host
  354.  
  355.            You can specify a host that is denied permission by entering an
  356.            exclamation point (!) followed by the name of the host name of the
  357.            host on a line.  ALL users on that host are denied permission,
  358.            regardless of subsequent lines.
  359.  
  360.            You may also use the IP address of the host instead (the dotted-
  361.            decimal representation).  If you specify the name of the host,
  362.            that name must appear in the HOSTS file used by your TCP/IP package.
  363.  
  364.    +user
  365.            You can specify a user name that is granted permission by entering
  366.            a plus sign (+) followed by the user name on a line.  Do not put
  367.            any spaces between the plus sign and the user name.  That user
  368.            will be granted permission regardless of the host (as long as
  369.            the host is not specifically denied).
  370.  
  371.            See below for an explanation of the source of the "user name" and
  372.            how it is validated.
  373.  
  374.    -user
  375.            You can specify a user name that is to be denied permission by
  376.            entering a minus sign (-) followed by the user name on a line.
  377.            Do not put any spaces between the plus sign and the user name.
  378.            That user will be denied permission on all hosts.
  379.  
  380.            See below for an explanation of the source of the "user name" and
  381.            how it is validated.
  382.  
  383.   +user@host
  384.  
  385.            You can specify a user name and a host that is granted permission
  386.            by entering a plus sign (+) followed by the user name, an at-sign
  387.            (@), followed by the host name on a line.  Do not put any spaces
  388.            between the plus sign and the user name or before or after the
  389.            at-sign.  That user on the specified host will be granted
  390.            permission, but only from that host.
  391.  
  392.            You may also use the IP address of the host instead (the dotted-
  393.            decimal representation).  If you specify the name of the host,
  394.            that name must appear in the HOSTS file used by your TCP/IP package.
  395.  
  396.   -user@host
  397.  
  398.            You can specify a user name and a host that is denied permission
  399.            by entering a minus sign (-) followed by the user name, an at-sign
  400.            (@), followed by the host name on a line.  Do not put any spaces
  401.            between the minus sign and the user name or before or after the
  402.            at-sign.  That user on the specified host will be denied
  403.            permission, but only when coming from that host.
  404.  
  405.            You may also use the IP address of the host instead (the dotted-
  406.            decimal representation).  If you specify the name of the host,
  407.            that name must appear in the HOSTS file used by your TCP/IP package.
  408.  
  409. If the request is coming from a Unix system, the user name is the login name
  410. of the user.  If the request is coming from another Windows PC, the method of
  411. specifying the user name is determined by the implementation of the "rsh" or
  412. "rcp" command you are using.
  413.  
  414. Note that the standard Unix "rsh" command (and the Winsock RSH command
  415. available from Denicomp Systems) allows a "-l" option to specify an alternate
  416. user name.  The "-l" option has meaning on a Unix system, but is not especially
  417. useful with Winsock RSHD.  However, if you do use the "-l" option to specify
  418. an alternate user, as with Unix, that user must be granted permission through
  419. the Security File in addition to the login name (Unix) or the name specified
  420. in your particular TCP/IP implementation (Windows/DOS).
  421.  
  422. USING THE SECURITY FILE
  423. -----------------------
  424.  
  425. To effectively use the Security File, you must first understand how it is
  426. viewed by Winsock RSHD.
  427.  
  428. When Winsock RSHD receives a request, it sequentially processes the lines
  429. in the Security File to determine whether or not the host and user is granted
  430. or denied access.  It looks at each line in the Security File until it
  431. determines that either the host or the user is specifically denied permission.
  432.  
  433. Winsock RSHD begins by assuming that permission is denied for the request.  It
  434. then examines the lines in the Security File to see if any of the lines
  435. pertain to this request.
  436.  
  437. Once Winsock RSHD finds a line that denies access to either the user or the
  438. host, it stops looking and denies permission.
  439.  
  440. If it finds a line that grants permission to the user and/or host, permission
  441. is tentatively granted, but it continues to process the lines in the Security
  442. File.
  443.  
  444. If it processes the entire Security File and does not find a line that grants
  445. permission to the user and/or the host, permission is denied.   If security
  446. was tentatively granted at some point and not denied subsequently, permission
  447. is granted.
  448.  
  449. For example, let's say that the following is the contents of the Security File:
  450.  
  451.            jetty
  452.            booey
  453.            eib
  454.            192.56.42.3
  455.            rs6000
  456.            +fred@mars
  457.            -gary@booey
  458.            -jackie
  459.            +robin
  460.  
  461. In this example, if any user on the host "jetty" makes a request,
  462. permission will be granted, unless the user is "jackie", since "jackie" is
  463. denied access from all hosts (-jackie).
  464.  
  465. If "jackie@jetty" makes a request, Winsock RSHD reads through the Security File
  466. and finds the host name "jetty", and tentatively grants permission.  However, it
  467. continues and finds that the user "jackie" is denied from all hosts, so
  468. permission is denied.
  469.  
  470. Also, if any user on the host "booey" makes a request, they are granted
  471. permission unless the user is "gary", since "gary@booey" is specifically
  472. denied permission (-gary@booey).  All other users on the host "booey" are
  473. granted permission except "jackie" (-jackie).
  474.  
  475. The user "fred" on the host "mars" is granted permission because of the
  476. line "+fred@mars".  However, since the host "mars" does not appear on
  477. a line by itself, no other users on the host "mars" are granted permission
  478. except the user "robin", who is granted permission from ANY host (+robin).
  479.  
  480. THE WINSOCK RSHD WINDOW
  481. -----------------------
  482.  
  483. The Winsock RSHD window displays information about connections to the PC.  You
  484. can use it to monitor access to the PC.
  485.  
  486. +-----------------------------------------------------------------------------+
  487. | = |                           Winsock RSHD                         | ^ | v  |
  488. +-----------------------------------------------------------------------------+
  489. |                                                                             |
  490. | Status:                                                                     |
  491. |    Accepting connections...                                                 |
  492. |                                                                             |
  493. | Last Connection:                                                            |
  494. |    Connected to rs6000 (89.0.0.10)                                          |
  495. |    Local User: tomf  Remote User: tomf                                      |
  496. |                                                                             |
  497. | Last Command:                                                               |
  498. |    <%FO\docs\invoice.doc~%FP~%FX> word                                      |
  499. |                                                                             |
  500. | Messages:                                                                   |
  501. |                                                                             |
  502. |                                                                             |
  503. |                                                                             |
  504. |                                                                             |
  505. |                                                                             |
  506. +-----------------------------------------------------------------------------+
  507.  
  508. The window contains the following sections:
  509.  
  510. Status:
  511.  
  512.       The current status of Winsock RSHD.
  513.  
  514. Last Connection:
  515.  
  516.       The host name (if found in the HOSTS file on the PC), the IP address,
  517.       the local user name, and remote user name of the last connection to
  518.       the PC through Winsock RSHD.
  519.  
  520. Last Command:
  521.  
  522.       The last command executed through Winsock RSHD.
  523.  
  524. Messages:
  525.  
  526.       A scrolling list of various messages displayed by Winsock RSHD.  The
  527.       messages that display here depend on the Message Level parameter in
  528.       the Winsock RSHD Configuration.  With the default Message Level of 0,
  529.       you will see notification of any permission violations or command
  530.       execution errors (i.e. command not found).
  531.  
  532. To stop Winsock RSHD, double-click on the button in the top left corner of
  533. the window or click on it once and choose "Close" from the menu.
  534.  
  535. To find the version of Winsock RSHD you are using, click once on the button
  536. in the top left corner of the window and choose "About" from the menu.
  537.  
  538. EXECUTING COMMANDS
  539. ------------------
  540.  
  541. With Unix, the "rsh" utility executes the specified command on a remote host
  542. and returns the standard output and the standard error output to the requesting
  543. host.
  544.  
  545. With Windows, there is no such thing as "standard output" and "standard
  546. error".  Programs execute in graphical windows, so there is no way to return
  547. any output using "rsh".  However, there is an option to capture the standard
  548. output and standard error output of MS-DOS programs.  This is explained later.
  549.  
  550. When using "rsh" from Unix or another PC to initiate commands on a Windows PC,
  551. by default you will not see any output of the command on your screen.  It
  552. will display on the PC that received the request.
  553.  
  554. For example, if you used the following command:
  555.  
  556.           rsh winpc3 excel
  557.  
  558. This would start Excel on the PC named "winpc3".  You would see nothing on your
  559. screen as a result of starting Excel.  Excel would be running on the screen of
  560. the PC named "winpc3".
  561.  
  562. The "rsh" command will NOT wait for the specified command to complete.  The
  563. system issuing the request will regain control immediately after the command
  564. begins, unless the command is a DOS program and Windows is not set up to
  565. exclusively execute the DOS command.
  566.  
  567. There is an option to wait for the command to complete before returning control
  568. to the system issuing the "rsh" command.  This is explained later.
  569.  
  570. If you attempt to execute a command that does not exist or Windows returns an
  571. error trying to load the program, you will receive a descriptive error message
  572. on your screen from Winsock RSHD to tell you that the command was not
  573. successfully executed.
  574.  
  575. UNREGISTRED VERSION NOTE:  The unregistered version of Winsock RSHD returns
  576. a message to the remote host about Winsock RSHD not being registered.  This
  577. does not occur in the registered version.
  578.  
  579.  
  580. SENDING KEYSTROKES
  581. ------------------
  582.  
  583. Winsock RSHD provides the ability for you to send keystrokes to the Windows
  584. application you initiate using the "rsh" command.  It also allows you to
  585. specify how the window is to be displayed (i.e. normal, minimized, maximized,
  586. or hidden).  This provides you with some "remote control" over what the
  587. program you run does once it starts.
  588.  
  589. For those of you who program in Microsoft Visual Basic or the Visual Basic for
  590. Applications macro language, this is very similar to the "SendKeys" capability
  591. of those programming languages.
  592.  
  593.  
  594. The standard syntax of the "rsh" command is:
  595.  
  596.              rsh hostname command
  597.  
  598. This will execute "command" on the host "hostname".  Winsock RSHD allows a
  599. slight modification of the "rsh" syntax to send keystrokes.  This is compatible
  600. with all "rsh" commands.  The alternative syntax for sending keystrokes is:
  601.  
  602.  
  603.              rsh hostname "<keystrokes>" command
  604.  
  605.  
  606. If the first parameter after the host name begins with a less-than sign (<),
  607. that parameter is interpreted as keystrokes to be sent to the command
  608. specified in the next parameter.  The keystrokes must end with a greater-than
  609. sign (>).  You must also enclose the entire parameter in quotes so special
  610. characters and spaces are not interpreted by the operating system.
  611.  
  612. For example, if you wanted to run the Windows Notepad on the PC named "winpc3"
  613. and type "This is a test" on the first line, the command would be:
  614.  
  615.              rsh winpc3 "<This is a test>" notepad
  616.  
  617. If you looked at the winpc3's screen, you would see the Windows Notepad with
  618. "This is a test" on the first line.
  619.  
  620. NOTE: You cannot send keystrokes to an application that is not designed to
  621.       run in Microsoft Windows (i.e. MS-DOS programs).
  622.  
  623.  
  624. SENDING SPECIAL KEYSTROKES
  625. --------------------------
  626.  
  627. Winsock RSHD also allows you to specify special keys in the keystrokes
  628. parameter that cannot normally be typed on a command line, such as embedded
  629. Enter keys, function keys, ALT keys, etc.
  630.  
  631. Keystrokes are sent sequentially as the appear between the "<" and ">".  To
  632. send a single character, use the character itself.  For example, to send the
  633. letter "X", use the letter "X".  To send the word "hello", just specify those
  634. letters.
  635.  
  636. To specify keys combined with any combination of Shift, Ctrl, and Alt keys,
  637. prefix the regular key code with one or more of the following codes:
  638.  
  639.             Shift      +
  640.             Control    ^
  641.             Alt        %
  642.  
  643. For example, to send the Alt-F keystroke, specify "%F".  To send Ctrl-Alt-D,
  644. specify "^%D".
  645.  
  646. To send the Enter key, use the tilde (~).
  647.  
  648. To specify that the Shift, Ctrl, and/or Alt keys should be held down while
  649. several other keys are pressed, enclose the key codes in parentheses ( ).
  650. For example, to have the Alt key held down while X and D are pressed, use
  651. "%(XD)".  You could also use "%X%D", but if the Shift, Ctrl, and/or Alt keys
  652. need to be held down for a number of keystrokes, the parentheses can make the
  653. string shorter.  Also, you would want to use the parentheses if the application
  654. detects the release of the Shift, Ctrl, and/or Alt keys and that is not desired.
  655.  
  656. The following characters have special meaning in the keystroke parameter, so
  657. they must be enclosed inside braces ({ }).  Some of these special characters
  658. have not been explained yet.
  659.  
  660.       Special Character             Example
  661.  
  662.           +  (plus)                   {+}
  663.           ^  (caret)                  {^}
  664.           %  (percent)                {%}
  665.           ~  (tilde)                  {~}
  666.           <  (less than)              {<}
  667.           >  (greater than)           {>}
  668.           [  (left sq. bracket)       {[}
  669.           ]  (right sq. bracket)      {]}
  670.           (  (left paren)             {(}
  671.           )  (right paren)            {)}
  672.           @  (at-sign)                {@}
  673.           {  (left brace)             {{}
  674.           }  (right brace)            {}}
  675.  
  676. To send characters that are not normally displayed when you press a key (such
  677. as Enter or Tab) and keys that represent actions rather than characters, use
  678. the following special codes:
  679.  
  680.    Key                Code                        Key           Code
  681.  
  682.    Backspace     {BACKSPACE} or {BS} or {BKSP}    Break        {BREAK}
  683.    Caps Lock     {CAPSLOCK}                       Clear        {CLEAR}
  684.    Del           {DELETE} or {DEL}                Down Arrow   {DOWN}
  685.    End           {END}                            Enter        {ENTER} or ~
  686.    Esc           {ESCAPE} or {ESC}                Help         {HELP}
  687.    Home          {HOME}                           Ins          {INSERT}
  688.    Left Arrow    {LEFT}                           Num Lock     {NUMLOCK}
  689.    Page Down     {PGDN}                           Page Up      {PGUP}
  690.    Print Screen  {PRTSC}                          Right Arrow  {RIGHT}
  691.    Scroll Lock   {SCROLLLOCK}                     Tab          {TAB}
  692.    Up Arrow      {UP}                             F1           {F1}
  693.    F2            {F2}                             F3           {F3}
  694.    F4            {F4}                             F5           {F5}
  695.    F6            {F6}                             F7           {F7}
  696.    F8            {F8}                             F9           {F9}
  697.    F10           {F10}                            F11          {F11}
  698.    F12           {F12}                            F13          {F13}
  699.    F14           {F14}                            F15          {F15}
  700.    F16           {F16}  
  701.  
  702. You can also specify that a key is to repeat itself a certain number of times,
  703. without repeating the key itself in the string.  To repeat a keystroke, use the
  704. format:
  705.  
  706.                     {keystroke number}
  707.  
  708. Where "keystroke" is the key to repeat, followed by a single space, then the
  709. number of times to repeat the key.
  710.  
  711. For example, to press the down arrow key 8 times, use "{DOWN 8}".  To type
  712. 30 *'s, use: "{* 30}".
  713.  
  714. KEYSTROKE EXAMPLE
  715. -----------------
  716.  
  717. The following example, will start Microsoft Word, load a file, print it,
  718. then exit.
  719.  
  720.            rsh winpc3 "<%FO\docs\invoice.doc~%FP~%FX>" word
  721.  
  722.  
  723. The keystrokes are:
  724.  
  725.                  %F   - Alt-F  (Drops down the file menu)
  726.                   O   - O      (Selects Open)
  727.   \docs\invoice.doc   - Types the filename.
  728.                   ~   - Enter  (Loads the File)
  729.                  %F   - Alt-F  (Drops down the file menu)
  730.                   P   - P      (Selects Print)
  731.                   ~   - Enter  (Accepts the defaults on the Print dialog box)
  732.                  %F   - Alt-F  (Drops down the file menu)
  733.                   X   - X      (Selects eXit and Word exits)
  734.  
  735.  
  736. Note that if this example were being run from a Unix system, you would have to
  737. use two backslashes (\\) for every one desired backslash because the Unix shells
  738. interpret the backslashes as special characters.  The command would then be:
  739.  
  740.            rsh winpc3 "<%FO\\docs\\invoice.doc~%FP~%FX>" word
  741.  
  742.  
  743. KEYSTROKE MACRO FILES
  744. ---------------------
  745.  
  746. If your keystroke strings get rather long or complex, you can store them in a
  747. keystroke macro file so you don't have to specify all of them each time you use
  748. the "rsh" command.
  749.  
  750. To create a keystroke macro file, you must use a text editor (or a word
  751. processor, but be sure to save as an ASCII file).  Enter the keystrokes as you
  752. would on the "rsh" command line, with the following exceptions/reminders:
  753.  
  754.      1) Do not enter "<" as the first character in the file or ">" as the
  755.         last character.  All of the characters you enter in the file will
  756.         be sent.
  757.  
  758.      2) You may press Enter in the file to enter the keystrokes on multiple
  759.         lines.  The line breaks have NO effect on the keystrokes.  They will
  760.         be treated as if they were entered all on the SAME LINE.  That is, you
  761.         must remember to still use "~" or "{ENTER}" to "press" the Enter key.
  762.         Pressing Enter in the file will NOT send the Enter key.
  763.  
  764.      3) You CANNOT nest keystroke macros.  Your macro file CANNOT contain
  765.         references to other keystroke macro files.
  766.  
  767.      4) The keystroke macro file MUST reside on the PC running Winsock RSHD.
  768.         You can create the file on that PC or use "rcp" to copy it to that
  769.         PC before executing the command.
  770.  
  771. To use a keystroke macro file, you enter the at-sign (@) followed by the
  772. filename in braces ({ }) where you would normally specify keystrokes on the
  773. "rsh" command line.
  774.  
  775. You will most likely need to specify a full pathname of the keystroke file
  776. on the PC running Winsock RSHD, unless you know the working directory
  777. of Winsock RSHD on the system running it and the keystroke macro resides
  778. in that directory.  You may use forward slashes (/) instead of backslashes
  779. if you wish; this makes life easier for Unix users because the shell
  780. interprets the backslash characters.
  781.  
  782. For example, if you had a macro in the directory \kbmac\printss.mac on the
  783. PC running Winsock RSHD, you could use it with this command:
  784.  
  785.             rsh winpc2 "<@{/kbmac/printss.mac}>" excel
  786.  
  787. This would run "excel" on winpc2 and send the keystrokes stored in the
  788. file \kbmac\printss.mac to it.
  789.  
  790.  
  791. You can intermix command line keystrokes and macro file keystrokes.  That is,
  792. you can specify some of the keystrokes on the command line and use some from
  793. a macro file.   You can also use multiple macro files.
  794.  
  795. For example, let's say we want to print a file using "rsh" through a Windows
  796. application called "wintiff".  We want to store the keystrokes in a macro
  797. file, but don't want to store the filename in the macro file because it can
  798. change.
  799.  
  800. To do this you can store the first set of keystrokes in one macro file,
  801. specify the filename on the "rsh" command line, then store the remaining
  802. keystrokes in a second file.
  803.  
  804. For example, let's say the file is "mypic.tif":
  805.  
  806.   rcp mypic.tif winpc2:/tmp
  807.   rsh winpc2 "<@{/kb/tifprt1.mac}\tmp\mypic.tif~@{/kb/tifprt2.mac}" wintiff
  808.  
  809. This example copies the file "mypic.tif" to the \tmp directory on winpc2.
  810. Then it runs "wintiff" and first sends the keystrokes from the file
  811. \kb\tifprt1.mac.  That macro ends when "wintiff" requires a filename.
  812. The keystrokes to "type" the filename come from the "rsh" command line
  813. since the tifprt1.mac has ended.  Then it continues by sending the keystrokes
  814. in the file \kb\tifprt2.mac.  That is:
  815.  
  816.     @{/kb/tifprt1.mac}  -  Send keystrokes from \kb\tifprt1.mac
  817.        \tmp\mypic.tif~  -  Type \tmp\mypic.tif and press Enter
  818.     @{/kb/tifprt2.mac}  -  Send keystrokes from \kb\tifprt2.mac
  819.  
  820.  
  821. SPECIFYING THE WINDOW TYPE
  822. --------------------------
  823.  
  824. Winsock RSHD also allows you to specify the window type of the application
  825. being run.  By default, the application is run "normally", as if you ran it
  826. by double-clicking on it's icon (assuming you did not set up the icon to run
  827. it minimized).
  828.  
  829. If you want to specify an different method of displaying the application's
  830. window, you can specify this inside the keystroke parameter by enclosing
  831. the method within square brackets ([ ]).
  832.  
  833. There are two methods of setting the window type.  You can use one of the
  834. words shown below or you can use a number.  The options are:
  835.  
  836.      Window Option                  Displays
  837.  
  838.       NORMAL                        Normal Display as defined by the application
  839.       MINIMIZE                      Shows the application as a minimized icon
  840.       MAXIMIZE                      Maximizes the application on startup
  841.       HIDE                          Hides the application (no icon appears)
  842.  
  843.       0                             Same as HIDE
  844.       1                             Same as NORMAL
  845.       2                             Same as MINIMIZE
  846.       3                             Same as MAXIMIZE
  847.  
  848. Other numeric values may be used - they correspond to the Windows' ShowWindow
  849. function (for all you programmers).
  850.   
  851. For example, if you want to run the Windows Notepad maximized, viewing the
  852. file "heyyou.txt", you would type:
  853.  
  854.            rsh winpc3 "<[MAXIMIZE]>%FOheyyou.txt~" notepad
  855.  
  856. This runs the Notepad maximized, then "presses" Alt-F-O (File Open) and
  857. types the filename "heyyou.txt" and presses Enter to load it.
  858.  
  859. If you wanted to run some application that does some task and exits, you
  860. could run it minimized using:
  861.  
  862.            rsh winpc3 "<[MINIMIZE]>" bkgprint
  863.  
  864. Note that Windows does not allow you to send keystrokes to a minimized
  865. or hidden application.  Therefore, "[MINIMIZE]", "[HIDE]", "[0]", or "[2]"
  866. should always appear alone between the "<" and ">".  If you specify other
  867. keystrokes, the application will not receive them (Windows will beep at you
  868. for each keystroke).
  869.  
  870.  
  871. WAITING FOR COMMANDS TO FINISH
  872. ------------------------------
  873.  
  874. By default, Winsock RSHD returns control to the system issuing the "rsh"
  875. command immediately after the command is started and any keystrokes are sent.
  876.  
  877. If you want the "rsh" command to wait until the command completes, you can
  878. specify the "[WAIT]" option.  This is specified like the Window Type parameter
  879. as explained in the previous section.
  880.  
  881. For example, to run the command "bkgprint" and wait for it to complete, use:
  882.  
  883.            rsh winpc3 "<[WAIT]>" bkgprint
  884.  
  885. You can combine Window Type options and keystrokes with the [WAIT] option.
  886. For example:
  887.  
  888.            rsh winpc3 "<[WAIT][MINIMIZE]>" bkgprint
  889.  
  890.  
  891. Note that when using the "[WAIT]" option, Winsock RSHD cannot process requests
  892. from other users while the command is executing.  It will queue the requests
  893. and process them when the command completes.  The number of requests it will
  894. queue depends on the "Listen Backlog" configuration option.
  895.  
  896.  
  897. CAPTURING STANDARD OUTPUT AND STANDARD ERROR
  898. --------------------------------------------
  899.  
  900. Programs for Microsoft Windows produce graphical output which cannot be sent
  901. to the system issuing the command.  However, some MS-DOS programs output
  902. information to the standard output and the standard error output.  You can
  903. capture this information and have it displayed or captured on the system
  904. issuing the command via "rsh".
  905.  
  906. To do this, you must use the "[DOS]" option when executing the command.  This
  907. option is specified like the Window Type and "[WAIT]" option as explained in
  908. the previous sections.
  909.  
  910. The "[DOS]" option tells Winsock RSHD that you are executing an MS-DOS program
  911. and you want it to capture the standard output and standard error output
  912. and send it over the network to the "rsh" command.  For example:
  913.  
  914.          rsh winpc3 "<[DOS]>" mem /c
  915.  
  916. This will run the MS-DOS "mem /c" command on "winpc3" and display the output on
  917. your screen.  Without the "[DOS]" option, the output will display on the PC
  918. running Winsock RSHD.
  919.  
  920. Note that not all MS-DOS programs use the standard output or standard error
  921. to display information.  Some write directly to the video memory; output
  922. from these programs cannot be captured.
  923.  
  924. The "[DOS]" option implies the "[WAIT]" option, so there is no need to specify
  925. it also.  Winsock RSHD must wait for the command to complete before sending
  926. the output.  This also means that the output will not display in "real time"
  927. as it is displayed by the command; it displays when the command is complete.
  928.  
  929. When the command completes, Winsock RSHD first sends all of the standard output
  930. to the "rsh" command, then the standard error output.  If you would like to
  931. reverse this order, you can use the "[DOS2]" option instead.  This sends the
  932. standard error output first, then the standard output.
  933.  
  934.  
  935. COPYING FILES USING RCP
  936. -----------------------
  937.  
  938. Winsock RSHD also provides Remote Copy (RCP) Server capability.  This allows
  939. you to copy files to and from a PC running Winsock RSHD using the "rcp"
  940. command.
  941.  
  942. The "rcp" command is commonly found on Unix systems and in some TCP/IP
  943. packages for Windows and DOS.  If your TCP/IP package does not provide the
  944. "rcp" command, you can use Winsock RCP from Denicomp Systems.
  945.  
  946. The "rcp" command is described in more detail in your TCP/IP package manual
  947. or with the manual that comes with Winsock RCP.  However, here are a few
  948. examples of its use.
  949.  
  950. To copy a file from the host named "srvpc" to your PC or Unix system, use:
  951.   
  952.             rcp srvpc:yourfile myfile
  953.   
  954. The file "yourfile" is copied from the host named "srvpc" to the file on your
  955. PC named "myfile".  The host "srvpc" could be running either Windows and
  956. Winsock RSHD or Unix.
  957.  
  958. To copy a file from your PC or Unix system to the PC named "srvpc", use:
  959.   
  960.             rcp \lists\xmas.doc srvpc:\word\lists
  961.   
  962. The file \lists\xmas.doc is copied from your system to the file xmas.doc in
  963. the directory \word\lists on the PC named "srvpc".
  964.  
  965.   
  966. To send the entire directory tree from your PC or Unix system to "srvpc", use:
  967.   
  968.              rcp -r \share srvpc:\
  969.   
  970. All of the files and subdirectories in the directory \share is copied to the
  971. PC named "srvpc".  It will create a \share directory in the root directory (\)
  972. of srvpc.
  973.  
  974. If the \share directory contained any subdirectories, they would be created
  975. on the other PC and all the files in them would also be copied.
  976.  
  977.  
  978. To copy all of the files ending with ".xls" from "srvpc" to your PC, use:
  979.  
  980.             rcp srvpc:\sheets\*.xls .
  981.  
  982. This copies all of the files ending with ".xls" in the directory \sheets on
  983. "srvpc" to the current directory (.) on your PC.
  984.  
  985.  
  986. You can use drive letters if necessary.  For example, to copy a file from
  987. the A: drive on the "srvpc" to your PC:
  988.  
  989.              rcp srvpc:a:file.txt file.txt
  990.  
  991. This will copy "file.txt" from the A: drive on "srvpc" to the file "file.txt"
  992. on your system.
  993.  
  994.  
  995. NOTE: Winsock RSHD allows you to use both slashes (/) and backslashes (\)
  996.       for directory separators.  It will adjust appropriately.  This is
  997.       especially important for Unix users, since backslashes are interpreted
  998.       by the shell and must be escaped by using two backslashes for every
  999.       one backslash.  Use slashes instead.
  1000.  
  1001.  
  1002. NOTES FOR SCO XENIX
  1003. -------------------
  1004.  
  1005. If you are using SCO Xenix with Excelan's LAN Workplace for Xenix, you may
  1006. receive error messages when using "rsh" and "rcp" to access a PC running
  1007. Winsock RSHD.  These error messages are basically harmless - both commands
  1008. work even though you receive an error message.
  1009.  
  1010. When using "rsh", you may receive an error about the "stdio" connection being
  1011. dropped.  If you do, you can stop this message by using the "-n" option of rsh.
  1012.  
  1013. For example, use:
  1014.  
  1015.          rsh winpc2 -n notepad
  1016.  
  1017. (If you are specifying keystrokes, they go AFTER the "-n").
  1018.  
  1019. When using "rcp", you may receive a socket error 104.  There is no work around
  1020. for this error message.  However, the files will all be copied successfully.
  1021. You can ignore this error message.
  1022.  
  1023.  
  1024. SHAREWARE NOTE
  1025. --------------
  1026.  
  1027. The unregistered version of Winsock RSHD is different from the registered
  1028. version in the following two ways:
  1029.  
  1030.     1) When you execute a command using "rsh", Winsock RSHD will return a
  1031.        message to the rsh command reminding you that Winsock RSHD is not
  1032.        registered.  This message will be displayed on the screen requesting
  1033.        the execution of the command.  This will not occur in the registered
  1034.        version.
  1035.  
  1036.     2) At random times on the PC running Winsock RSHD, when Winsock RSHD
  1037.        receives a command request it will require you to click on an "OK"
  1038.        button in a screen that reminds you that Winsock RSHD is not registered.
  1039.  
  1040.        This will also cause the "rsh" or "rcp" command on the requesting system
  1041.        to ALSO PAUSE until "OK" is clicked on the server PC.  The command WILL
  1042.        be completed once "OK" is clicked on the server.
  1043.  
  1044.        This will not occur more than once per hour.
  1045.  
  1046.  
  1047. WINSOCK RSHD CONFIGURATION FILE
  1048. -------------------------------
  1049.  
  1050. Configuration information for Winsock RSHD is stored in the file WRSHD.INI.
  1051. This file must be placed in the Windows directory (usually \WINDOWS).
  1052.  
  1053. This file is normally created and modified by the Winsock RSHD Configuration
  1054. program.  However, you may modify it manually using a text editor.  This section
  1055. shows the configuration options that may be placed in the WRSHD.INI file for
  1056. those who prefer to configure it manually.
  1057.  
  1058. If WRSHD.INI does not exist in the Windows directory, default values are
  1059. assumed for all options.  No WRSHD.INI file is provided with the Winsock RSHD
  1060. distribution.  If you wish to change any of the default values, you must either
  1061. use the Configuration program or create the file with your favorite text editor.
  1062.  
  1063. The WRSHD.INI consists of one section called "[Setup]".  The configuration
  1064. options must appear after a line that contains "[Setup]".
  1065.  
  1066. The configuration options are specified in the format:
  1067.  
  1068.          Option=Value
  1069.  
  1070. Each of the options were explained in detail earlier in the section on WINSOCK
  1071. RSHD CONFIGURATION.  The following gives the Option names:
  1072. The options are:
  1073.  
  1074. Screen Title                  Option Name
  1075. ------------                  -----------
  1076. Method                        Method
  1077. Minimize on Startup           MinimizeOnStartup
  1078. Message Level                 MessageLevel
  1079. Security File                 SecurityFile
  1080. Request Log                   RequestLog
  1081. Deny Log                      DenyLog
  1082. Error Log                     ErrorLog
  1083. Port                          Port
  1084. RCP Block Size                RCPBlockSize
  1085. Listen Shutdown               ListenShutdown
  1086. Listen Backlog                ListenBacklog
  1087. Listen Linger                 ListenLinger
  1088. Listen KeepAlive              ListenKeepAlive
  1089. Listen ReuseAddr              ListenReuseAddr
  1090. Connection Linger             ConnLinger
  1091. Connection KeepAlive          ConnKeepAlive
  1092. Connection ReuseAddr          ConnReuseAddr
  1093. Connection Shutdown           ConnShutdown
  1094. Stderr Linger                 StderrLinger
  1095. Stderr KeepAlive              StderrKeepAlive
  1096. Stderr ReuseAddr              StderrReuseAddr
  1097. Stderr Shutdown               StderrShutdown
  1098.  
  1099.  
  1100. EXAMPLE WINSOCK RSHD CONFIGURATION FILE
  1101. ---------------------------------------
  1102.  
  1103. The following is an example of the contents of a WRSHD.INI file:
  1104.  
  1105.  
  1106.         [Setup]
  1107.         MinimizeOnStartup=1
  1108.         SecurityFile=C:\WINDOWS\WRSHD.SEC
  1109.         DenyLog=C:\WRSHD\DENY.LOG
  1110.  
  1111.  
  1112. SUPPORT
  1113. -------
  1114.  
  1115. Support is available via U.S. Mail and Compuserve/Internet.
  1116.  
  1117. Denicomp Systems
  1118. P.O. Box 731
  1119. Exton, PA  19341
  1120.  
  1121. Compuserve: 71612,2333
  1122. Internet:   71612.2333@compuserve.com
  1123.  
  1124.